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A free data-analysis framework for fiSK has been developed, musrf it is fully written in C++, is 
running under GNU/Linux, Mac OS X, as well as Microsoft Windows, and is distributed under the 
terms of the GNU GPL. It is based on the CERN ROOT framework and is utilizing the Minuit2 
optimization routines for fitting. It consists of a set of programmes allowing the user to analyze 
and visualize the data. The fitting process is controlled by an ASCII-input file with an extended 
syntax. A dedicated text editor is helping the user to create and handle these files in an efficient way, 
execute the fitting, show the data, get online help, and so on. A versatile tool for the generation of 
new input files and the extraction of fit parameters is provided as well, musrf it facilitates a plugin 
mechanism allowing to invoke user-defined functions. Hence, the functionality of the framework 
can be extended with a minimal amount of overhead for the user. Currently, musrf it can read 
the following facility raw-data files: PSI-BIN, MDU (PSI), ROOT (LEM/PSI), WKM (outdated ASCII 
format), MUD (TRIUMF), NeXus (ISIS). 



INTRODUCTION 

Currently, various data-analysis tools for analyzing 
muon-spin-rotation (/iSR) data are available, however, 
the situation is unsatisfactory for different reasons. Most 
of these programmes are limited to a single platform, e. g. 
Microsoft Windows, others are not maintained anymore, 
and some of them are not free software. Another problem 
arising from this situation is that more elaborate mod- 
elling is almost impossible from within the current frame- 
works and hence, the users are forced to write their own 
code. This was especially true for low-energy ^SR (LE- 
fiSR) where often the /i + stopping distribution has to be 
taken into account in the analysis. Therefore, we started 
to develop a free data-analysis framework for ^SR, called 
musrf it, which should overcome the problems described. 

From the points raised, the design criteria were: (i) 
musrf it has to be free software according to the GNU 
licenses pQ, and hence available to everyone, (ii) It should 
be transparent and user-friendly, e. g. a clear and com- 
plete online documentation should be available, (iii) Ex- 
tensions to the basic framework should be possible on 
the user level, (iv) musrf it should be able to read all 
currently used /zSR-data-file formats directly, (v) Data- 
visualization and fit-parameter tools should be available, 
(vi) The maintainability should be warranted. 

In order to fulfil all these requirements we decided to 
build up on the ROOT framework [2] developed and main- 
tained at CERN and heavily used in particle physics 
as well as other fields of physics and engineering. The 
ROOT framework is a collection of C++ libraries together 
with a C++ macro interpreter. It provides graphical-user- 
interface tools and contains the Minuit/Minuit2 opti- 
mization routines [3]. For us it is a "natural" choice 
since the ROOT framework is already part of the /iSR- 
data-acquisition systems at PSI. musrf it consists of a 
collection of C++ classes [4] which can be used either di- 
rectly using the ROOT macro capabilities, or — probably 



simpler for most of the users — can be accessed via some 
user-friendly programmes, provided within the musrf it 
suite described in the next section. 



THE MUSRFIT SUITE 

The analysis of /iSR data using the musrf it suite is 
controlled by text files with the extension msr ("msr 
files"). These human- readable files contain all informa- 
tion needed to fit a model function to the ^SK data: the 
fit parameters, the definition of the model, some details 
on the relevant ^tSR data files, and the fitting routines 
to be used. Moreover, information used for the graphical 
presentation of the data and fits, such as plot ranges and 
parameters for Fourier transforms are stored in the msr 
files as well. These msr files are also used as a protocol 
of the fit results. A detailed explanation of the struc- 
ture and syntax of the msr files can be found in Ref. [5]. 
In the following, only a basic overview of the different 
programmes shall be given. 

musrf it — fitting a model 

After musrf it is called to fit a model it analyzes the 
respective msr file and reads in all specified data files. 
Successively, the fit is performed and the resulting pa- 
rameters are written to a mlog file which also complies 
with the msr file structure. Additionally, the covariance 
matrix and the correlation coefficients of the free fit pa- 
rameters as determined by Minuit2 are saved as ASCII 
and binary ROOT files. In a final step, the msr and mlog 
files are swapped so that the msr file contains the updated 
parameter values while the mlog file holds a copy of the 
parameter set used as input to musrf it. This procedure 
is summarized in Fig. [l] Currently, musrf it supports \ 2 
minimization and log-likelihood maximization. 
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ln-37 B=~48(G)/1 .49(A), T=2.83(K), Tr=15.02(kV), Sa=-0.01(kV), En=14.13(keV), RAL-RAR=0.01(kV), RAT-RAB=0.04(kV) 




mlog file Minuit2 output files 

FIG. 1. General file flow during a fit using musrf it. 

musrview — graphical presentation 

The analyzed data and the model functions can be vi- 
sualized using the programme musrview. Like the actions 
of musrf it also the initial plotting frame of musrview is 
controlled by the msr file. For example, it can be speci- 
fied which data should be drawn in which range; if more 
than one set of data should be drawn it can be chosen if 
they should appear in a single canvas or in separate ones, 
and so on. Since the plotting routines are based on ROOT 
as well, the initially drawn graphs can be easily modified 
using conventionai ROOT editing features — e. g. labels or 
arrows could be added, colours could be changed, and 
so on. musrview also offers the possibility to calculate 
and show the Fourier transforms of /iSR time spectra. 
As an example, Fig. [2] depicts the time spectrum and the 
corresponding field distribution of a selected fiSH mea- 
surement plotted by musrview. Despite not being shown 
in Fig. [2] also the difference between the analyzed data 
and a given model can be plotted. Furthermore, a set of 
keyboard shortcuts has been implemented to make the 
navigation more easy, e.g. pressing 'f toggles between 
the data presentation in the time and frequency domains, 
'd' changes the view to the difference plot. Finally, there 
also exists the possibility to save the shown data and 
model curves in an ASCII file which facilitates the fur- 
ther use of these data in the user's favourite programme. 



msr2data — advanced msr-file handling 

The musrf it suite also hosts a tool called msr2data. 
Its main purpose is to process multiple msr files with 
the same parameters and to summarize the fit parame- 
ters contained in the msr files cither in a TRIUMF DB 
file [6] or a column ASCII file. Moreover, msr2data can 
be used to generate from a template new msr files and 
even a "global" msr file for various runs sharing a subset 
of common parameters; for details on the "global" msr- 




musrfil: 2011-03-24, 17:51:20, chisq = 153.921369 , NOF - 157 , chisq/NDF = 0.98039000535031049 

O 2009/lem09_his_0906,h:1/3,T=2.B3K,B=47.44G,E=14.13keV,Sample, Bpar, LowTemp-2 

:~48(G)/1 .49(A), T=2.83(K), Tr=15.02(kV), Sa=-0.01(kV), En=14.13(keV), RAL-RAR=0.01(kV), RAT-RAB=0.04(kV) 
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musffil: 2011-03-24, 17:51:23, chisq = 153.921369 , NOF = 157 , chisq/NDF = 0.98039000535031049 

O 2009/lem09_his_0006,h:1/3,T=2.63K,B=47.44G,E=14.13keV,Sample, Bpar, LowTemp-2 



FIG. 2. Left panel: Time spectrum of selected fiSK data plot- 
ted using musrview. Right panel: Corresponding magnetic- 
field distribution. In both cases, the solid lines represent the 
fitted model. Both graphs contain information on the fit pa- 
rameters (upper right box), the model function (lower right 
box), the fit statistics as well as the plotted data (bottom 
box). 



file handling refer to Ref. [5]. 

Figure [3]Ja) shows schematically the parameter extrac- 
tion from different msr files. msr2data is provided with 
a list of runs to be processed; optionally, external param- 
eters which should be included in the resulting parameter 
file can be specified for each of the runs. Also optionally, 
parameters potentially stored in the [iSR data files (tem- 
perature, applied magnetic field, and so on) can be asked 
to be included. msr2data then reads the msr files for all 
given runs and adds all the parameter information to a 
parameter file. Figure (3^b) illustrates the msr-file gen- 
eration using a template — essentially, new msr files are 
created by substituting the run number in the template. 
It is possible as well to combine the above described ac- 
tions: a template can be used to create new msr files 
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FIG. 3. (a) msr2data used for extracting fit parameters from 
a list of msr files and summarizing them in a parameter file. 
The files sketched in blue with broken frames can be specified 
optionally, (b) msr2data used for generating new msr files 
from a template. 
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FIG. 4. Screenshot of a musredit window. The most impor- 
tant musrf it features are highlighted. 



for a list of runs, these files in turn are processed by 
musrf it, and finally the parameters of each of the files 
are summarized automatically in a parameter file. A de- 
tailed description of all possible options can be found in 
Ref. 0. 



User-defined functions 

Additionally to providing a set of pre-defined muon- 
spin-polarization functions, the musrf it suite facilitates 
a plug-in mechanism allowing it to invoke user-defined 
functions implemented in C++ classes [5]. Hence, the 
functionality of the programmes can be extended with 
a minimal amount of overhead for the user. For exam- 
ple, for the analysis of LE-/iSR data it is sometimes de- 
sirable to take into account the muon stopping distribu- 
tion in the calculation of the depolarization function — 
the plug-in mechanism offers a possibility to do so. A 
couple of such add-on modules are already available to- 
gether with musrf it, e.g. for modelling data obtained 
from superconductors which exhibit local [5j or nonlo- 
cal [9] Meissner screening of an applied magnetic field 
below their surfaces. It should be noted as well, that the 
so-defined plug-in classes are of course not limited to the 
use within musrf it; for instance, one could think about 
reusing them in other programmes or ROOT macros. 



any2many — a "universal" /iSR-data-file converter 

The musrf it suite reads the currently available fiSK 
data files without any conversion necessary. However, 
users might favour their own analysis software but have 
difficulties with all the different /iSR facility data-file for- 
mats. Hence, the small helper programme any2many is 
included in the musrf it suite which allows virtually all 
possible conversions from one format into another, in- 
cluding ASCII output. 
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musredit /musrgui — editing msr files 

Even though the msr files can naturally be edited 
with any text editor and the various programmes of the 
musrf it suite can be called from the command line, 
with musredit /musrgui dedicated text editors which 
also serve as frontends for the musrf it framework are 
provided. These are specifically intended to help the 
user handle msr files. Principally, musredit and musrgui 
have the same capabilities, however, they are based on 
different versions of Qt [TJ: musrgui — Qt3, musredit — 
Qt 4 . 6 or newer. Both programmes feature basic editor 
functions as well as interfaces to musrf it and are docu- 
mented in Ref. |S]. A screenshot of musredit indicating 
the most important musrf it features accessible through 
the editor is shown in Fig. [4| 



We are indebted to Z. Salman, T. Prokscha, 
H. Luctkcns, and R. Scheuermann for helpful discus- 
sions, suggestions, and bug reporting. Thanks to D. Ar- 
sencau for releasing MUD under the GNU LGPL Q], and 
S. Cottrell for the discussion and information provided 
on NeXus. 



REFERENCES 



* andreas.suter@psi.ch 
[I] http://www.gnu.org/licenses/ 

[2] R. Brun and F. Rademakers, Nucl. Instrum. Methods 
Phys. Res., Sect. A 389, 81-86 (1997). 
http : //root . cern. ch/ 



4 



[3] F. James and M. Roos, Comput. Phys. Commun. 10, [8] R. F. Kiefl, M. D. Hossain, B. M. Wojek, S. R. Dunsiger, 
343-367 (1975). G. D. Morris, T. Prokscha, Z. Salman, J. Baglo, D. A. 

http : //seal . web . cern . ch/ seal/MathLibs/Mimiit2/html/ indexBtotmfl, R. Liang, W. N. Hardy, A. Suter, and E. Morenzoni, 

[4] http ://lmu. web. psi.ch/facilities/software/musrfit/techniE4i|^iiaBK.Btai, 180502 (2010). 

[5] http://lmu.web.psi.ch/facilities/software/musrfit/use^iMeSutenvLE. Morenzoni, N. Garifianov, R. Khasanov, 
[6] http://musr.org/xyfit/dbformat.html E. Kirk, H. Luetkens, T. Prokscha, and M. Horisberger, 

[7] http://qt.nokia.com/ Phys. Rev. B 72, 024506 (2005). 



